﻿========================================================================
  Oracle2PostgreSQL - DB移行ツール  Version 0.1.0
========================================================================

  ソフト名     : Oracle2PostgreSQL - DB移行ツール
  バージョン   : 0.1.0
  作 者        : highdefinitionaudiodriver
  動作環境     : Windows 10/11, macOS 12+, Linux / Python 3.10 以上
  ライセンス   : MIT License（フリーソフト／オープンソース）
  種 別        : フリーソフト
  作成日       : 2026-06-09

------------------------------------------------------------------------
■ ソフトの説明 / 使用方法（README より）
------------------------------------------------------------------------

Oracle2PostgreSQL

Oracle → PostgreSQL 移行前の SQL / PL/SQL 資産診断・変換支援ツール

Oracle SQL / PL/SQL ファイルを構文解析し、80 以上の変換ルールで PostgreSQL 互換 SQL への変換候補を生成します。
GUI（Tkinter）・CLI・Docker の 3 モードに対応し、変換可能箇所・要レビュー箇所・手修正が必要な箇所を HTML / CSV レポートとして可視化します。

> Oracle ライセンス削減、クラウド移行、ベンダーロックイン回避を検討する企業向けに、移行前の資産棚卸し・難易度評価・概算工数見積もりを支援します。

---

🎯 これは何？（30秒で）

- 誰のため：Oracle DB を運用している社内 SE・DBA／クラウド移行（Aurora PostgreSQL 等）を検討中の情シス／SI ベンダーのアセスメント担当
- 何が解決される：Oracle→PostgreSQL 移行の 事前工数見積もりを「2週間の手作業」から「数時間の自動レポート」 に短縮。AWS SCT で漏れる PL/SQL の手修正範囲を可視化
- なぜ既存ツールではダメか：AWS SCT・ora2pg 等は変換そのものに寄っており、「上司に出せる移行リスク評価レポート」 が出ない。本ツールは HTML/CSV で 未対応構文 Top N・難易度スコア・概算工数 を出力
- 使う条件：Python 3.10+ / Windows・macOS・Linux／GUI・CLI・Docker いずれも可

💰 想定ユースケース・価格帯

| 用途 | 形態 |
|---|---|
| OSS としての利用（自社内で診断ツールを回す） | 無料（MIT） |
| 100 ファイル規模の 診断レポート受託（A4 PDF 納品） | 応相談（数万円〜） |
| エンタープライズ移行案件の アセスメント支援（追加ルール・カスタム変換） | 個別見積もり |

---

🎬 デモ / まず見るもの

<!-- docs/demo.gif に「Oracle SQLフォルダ選択 → 診断実行 → HTML/CSVレポート確認」までの30秒デモGIFを配置してください。 -->

移行前アセスメントだけを素早く見せる場合：


python scripts/diagnose.py examples/sample_oracle_app --html oracle_migration_summary.html


出力される HTML / CSV は、営業提案・稟議・見積もり前の初期判断資料として使えます。

---

Overview / 概要

データベースを Oracle から PostgreSQL へ移行する際、大量の DDL・DML・PL/SQL を手作業で棚卸し、変換可否を判断するには膨大な労力を要します。
Oracle2PostgreSQL は、この初期診断と変換たたき台作成を支援する Python 製ツールです。

Business Use / 活用シーン

- Oracle 脱却・PostgreSQL 移行の初期調査
- SQL / PL/SQL 資産の変換率、リスク、手修正ポイントの可視化
- 移行プロジェクトの概算工数・見積もり資料作成
- AWS SCT / DMS などの標準移行ツールで残る複雑な SQL の事前洗い出し

なぜ AST ベースなのか

単純な正規表現による文字列置換ではなく、Oracle SQL を 抽象構文木 (AST) にパースしてから変換を行います。
これにより、文字列リテラル内の誤置換を防ぎ、テーブル定義・制約・PL/SQL ブロックの構造を正確に把握した上で変換できます。

変換の 3 段階パイプライン


┌──────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────┐
│  Oracle  │────▶│ OracleParser │────▶│  Transformer │────▶│ Generator│
│  .sql    │     │  (AST 生成)  │     │ (80+ ルール) │     │ (_pg.sql)│
└──────────┘     └──────────────┘     └──────────────┘     └──────────┘
                                                                 │
                                                                 ▼
                                                          ┌──────────────┐
                                                          │ HTML/CSV     │
                                                          │ レポート生成 │
                                                          └──────────────┘


各変更には AUTO（自動変換済み）/ REVIEW（要確認）/ MANUAL（手動対応必須）の重要度が付与され、
レポートで一覧化されます。

---

Features / 主な機能

- 80+ 変換ルール — データ型、関数、構文、PL/SQL、トリガー、シーケンス、シノニムを網羅
- AST ベース解析 — CREATE TABLE / INDEX / VIEW / SEQUENCE / SYNONYM / PROCEDURE / FUNCTION / PACKAGE / TRIGGER を構造的にパース
- PL/SQL → PL/pgSQL 変換 — パラメータ、例外処理、カーソル、DBMS_OUTPUT 等を自動変換
- トリガー分離変換 — Oracle トリガーを PostgreSQL の「関数 + CREATE TRIGGER」形式に分離
- パッケージ変換ガイド — PACKAGE を Schema + 個別関数へ変換するガイドコメントを自動挿入
- HTML / CSV 移行レポート — 変更一覧、重要度別集計、ファイル別詳細を出力
- 59 言語 i18n — 日本語・英語・中国語・韓国語・フランス語など 59 言語の GUI / レポート
- YAML 設定ファイル — ルール ON/OFF、スキーママッピング、ログレベルを外部設定化
- 構造化ロギング — RotatingFileHandler によるファイルログ + コンソール出力
- GUI / CLI / Docker — 3 つの実行モードに対応
- CI/CD 対応 — GitHub Actions による自動テスト + Docker ビルド検証

---

Architecture / アーキテクチャ

ディレクトリ構造


Oracle2PostgreSQL/
├── main.py                     # エントリーポイント（GUI + CLI）
├── config.yaml                 # 設定ファイルテンプレート
├── pyproject.toml              # パッケージ設定
├── requirements.txt            # Python 依存パッケージ
├── Dockerfile                  # マルチステージ Docker ビルド
├── docker-compose.yml          # migration + test + postgres サービス
├── test_conversion.py          # テストスイート（39 テスト）
│
├── src/                        # コアモジュール
│   ├── __init__.py
│   ├── oracle_parser.py        # Oracle SQL/PL-SQL パーサー（AST 生成）
│   ├── migration_rules.py      # 80+ 変換ルール定義
│   ├── postgres_transformer.py # 変換エンジン（ルール適用）
│   ├── postgres_generator.py   # PostgreSQL 出力ファイル生成
│   ├── report_generator.py     # HTML/CSV レポート生成
│   ├── config_loader.py        # config.yaml ローダー
│   ├── logger.py               # 構造化ロガー
│   └── i18n.py                 # 59 言語国際化
│
├── samples/                    # サンプル Oracle SQL（7 ファイル）
│   ├── 01_create_tables.sql
│   ├── 02_sequences_indexes.sql
│   ├── 03_views_synonyms.sql
│   ├── 04_plsql_procedures.sql
│   ├── 05_packages.sql
│   ├── 06_triggers.sql
│   └── 07_queries.sql
│
├── .github/workflows/
│   └── ci.yml                  # GitHub Actions CI パイプライン
│
├── output/                     # 変換結果出力先
└── logs/                       # ログファイル出力先


コアモジュールの役割

| モジュール | 役割 |
|-----------|------|
| oracle_parser.py | Oracle SQL を AST（OracleSchema）にパース。テーブル・カラム・制約・PL/SQL ブロックを構造化 |
| migration_rules.py | 80+ の変換ルールを MigrationRule データクラスで定義。カテゴリ・重要度・正規表現パターンを管理 |
| postgres_transformer.py | AST にルールを適用し変換。各変更を ChangeRecord として記録 |
| postgres_generator.py | 変換結果をファイル出力。ヘッダーコメント・変更サマリーを付与 |
| report_generator.py | 全ファイルの変更を集計し HTML / CSV レポートを生成 |
| config_loader.py | config.yaml を読み込み型安全な AppConfig データクラスへ変換 |
| logger.py | コンソール + RotatingFileHandler のデュアル出力ロガー |

---

Conversion Rules / 変換ルール一覧

データ型変換（DATATYPE）

| Oracle | PostgreSQL | ルール ID |
|--------|-----------|----------|
| VARCHAR2(n) | VARCHAR(n) | DT_001 |
| NVARCHAR2(n) | VARCHAR(n) | DT_002 |
| NUMBER(p) | NUMERIC(p) | DT_003 |
| NUMBER(p,s) | NUMERIC(p,s) | DT_004 |
| NUMBER (無精度) | NUMERIC | DT_005 |
| DATE | TIMESTAMP | DT_006 |
| CLOB / NCLOB | TEXT | DT_007/008 |
| BLOB | BYTEA | DT_009 |
| RAW(n) | BYTEA | DT_010 |
| LONG RAW | BYTEA | DT_011 |
| XMLTYPE | XML | DT_013 |
| BINARY_FLOAT | REAL | DT_015 |
| BINARY_DOUBLE | DOUBLE PRECISION | DT_016 |
| BFILE | TEXT (パス参照) | DT_017 |

関数変換（FUNCTION）

| Oracle | PostgreSQL | ルール ID |
|--------|-----------|----------|
| SYSDATE | CURRENT_TIMESTAMP | FN_001 |
| NVL(a, b) | COALESCE(a, b) | FN_003 |
| NVL2(a, b, c) | CASE WHEN a IS NOT NULL ... | FN_004 |
| DECODE(...) | CASE ... (要手動) | FN_005 |
| TO_DATE(...) | TO_TIMESTAMP(...) | FN_006 |
| SUBSTR(...) | SUBSTRING(...) | FN_008 |
| INSTR(...) | POSITION(...) | FN_009 |
| SYS_GUID() | gen_random_uuid() | FN_011 |
| ADD_MONTHS(...) | + INTERVAL 'n months' | FN_013 |
| ROWNUM | ROW_NUMBER() OVER() (要手動) | FN_017 |
| seq.NEXTVAL | nextval('seq') | FN_019 |
| seq.CURRVAL | currval('seq') | FN_020 |
| MINUS | EXCEPT | SX_002 |

構文変換（SYNTAX）

| Oracle | PostgreSQL | 種別 |
|--------|-----------|------|
| FROM DUAL | (削除) | AUTO |
| /*+ HINT */ | (削除 + コメント) | AUTO |
| (+) 外部結合 | LEFT/RIGHT JOIN (要手動) | REVIEW |
| CONNECT BY | WITH RECURSIVE (要手動) | MANUAL |
| STORAGE(...) / TABLESPACE | (削除) | AUTO |
| GLOBAL TEMPORARY | TEMPORARY | AUTO |

PL/SQL 変換（PLSQL）

| Oracle PL/SQL | PostgreSQL PL/pgSQL | 種別 |
|--------------|-------------------|------|
| IS / AS (プロシージャ冒頭) | AS $$ | AUTO |
| END proc_name; | $$ LANGUAGE plpgsql; | AUTO |
| DBMS_OUTPUT.PUT_LINE | RAISE NOTICE | AUTO |
| RAISE_APPLICATION_ERROR | RAISE EXCEPTION | AUTO |
| EXECUTE IMMEDIATE | EXECUTE | AUTO |
| :NEW.col / :OLD.col | NEW.col / OLD.col | AUTO |
| PACKAGE | Schema + 個別関数 (要手動) | MANUAL |

---

Quick Start / クイックスタート

前提条件

- Python 3.11 以上
- （GUI 使用時）Tkinter（多くの Python ディストリビューションに同梱）
- （Docker 使用時）Docker / Docker Compose

インストール


リポジトリのクローン
git clone <repository-url>
cd Oracle2PostgreSQL

方法 A: pip でパッケージインストール（推奨）
pip install -e .

方法 B: requirements.txt から直接インストール
pip install -r requirements.txt


最小実行例


サンプル Oracle SQL を変換
oracle2pg -i samples -o output --lang ja

または直接実行
python main.py -i samples -o output --lang ja


output/ ディレクトリに変換済み *_pg.sql と HTML / CSV レポートが生成されます。

---

Usage / 使い方

CLI Mode


基本
oracle2pg -i /path/to/oracle-sql -o /path/to/output

設定ファイル指定 + 日本語レポート
oracle2pg -i ./input -o ./output -c config.yaml --lang ja

特定カテゴリをスキップ
oracle2pg -i ./input -o ./output --no-plsql --no-triggers

エンコーディング指定（Shift_JIS のソースファイル）
oracle2pg -i ./input -o ./output -e shift_jis


CLI オプション一覧：

| オプション | 説明 | デフォルト |
|-----------|------|----------|
| -i, --input | 入力ディレクトリ（Oracle SQL） | (必須) |
| -o, --output | 出力ディレクトリ（PostgreSQL） | (必須) |
| -c, --config | 設定ファイルパス | config.yaml |
| -e, --encoding | ファイルエンコーディング | utf-8 |
| --extensions | 対象ファイル拡張子（カンマ区切り） | .sql,.pls,... |
| --lang | 出力言語 | en |
| --no-datatypes | データ型変換をスキップ | |
| --no-plsql | PL/SQL 変換をスキップ | |
| --no-sequences | シーケンス変換をスキップ | |
| --no-synonyms | シノニム変換をスキップ | |
| --no-packages | パッケージ変換をスキップ | |
| --no-triggers | トリガー変換をスキップ | |
| --no-report | レポート生成をスキップ | |
| --no-backup | バックアップ作成をスキップ | |

GUI Mode


引数なしで起動すると GUI が立ち上がります
oracle2pg
または
python main.py


GUI では以下の操作が可能です：

1. 入力 / 出力フォルダを「参照...」ボタンで選択
2. 設定ファイル（config.yaml）を読み込んでチェックボックスに自動反映
3. 言語セレクタで 59 言語から UI 言語を切り替え
4. 「変換」ボタンでバックグラウンド実行（キャンセル可能）
5. ログ画面でリアルタイムの変換状況を確認

Docker Mode


イメージビルド
docker compose build

サンプル SQL を変換（PostgreSQL 検証コンテナも起動）
docker compose up migration

テストスイート実行
docker compose run --rm test

変換結果を PostgreSQL で検証
docker compose exec postgres psql -U migration -d migration_test

任意のディレクトリを変換
docker run --rm \
  -v /path/to/oracle-sql:/app/input:ro \
  -v /path/to/output:/app/output \
  oracle2pg:latest \
  -i /app/input -o /app/output --lang ja

クリーンアップ
docker compose down -v


---

Configuration / 設定ファイル

config.yaml で変換の挙動を細かくカスタマイズできます。

主要セクション

ルールカテゴリ ON/OFF


rules:
  categories:
    DATATYPE: true      # データ型変換
    FUNCTION: true      # 関数マッピング
    SYNTAX: true        # 構文変換
    PLSQL: true         # PL/SQL → PL/pgSQL
    SEQUENCE: true      # シーケンス構文
    TRIGGER: true       # トリガー変換
    SYNONYM: true       # シノニム変換


個別ルールの無効化


rules:
  # 特定ルールを ID 指定で無効化
  disabled_rules: ["FN_005", "DT_006"]


スキーママッピング


schema_mapping:
  HR: "public"          # HR.employees → public.employees
  SCOTT: "public"
  FINANCE: "finance"    # FINANCE.accounts → finance.accounts


ログ設定


logging:
  console_level: "INFO"       # コンソール出力レベル
  file_level: "DEBUG"         # ファイル出力レベル（詳細）
  log_file: "logs/migration.log"
  max_bytes: 5242880          # 5MB でローテーション
  backup_count: 3             # 3 世代保持


エンコーディング


general:
  input_encoding: "shift_jis"   # 日本語レガシー環境
  output_encoding: "utf-8"      # 出力は UTF-8


---

Migration Report / 移行レポート

変換完了後、output/ ディレクトリに以下のレポートが生成されます：

- migration_report_YYYYMMDD_HHMMSS.html — ブラウザで閲覧可能なリッチレポート
- migration_report_YYYYMMDD_HHMMSS.csv — Excel / スプレッドシートで分析可能な CSV

HTML レポートの構成

| セクション | 内容 |
|-----------|------|
| Executive Summary | ファイル数、総変更数、AUTO / REVIEW / MANUAL の集計カード |
| Changes by Category | DATATYPE / FUNCTION / SYNTAX 等のカテゴリ別集計テーブル |
| Review / Manual Items | 要確認・手動対応の全項目一覧（ファイル名・行番号・ルール ID） |
| File Details | ファイルごとの変更詳細 |

---

Limitations / Known Issues / 制限事項

Oracle2PostgreSQL は移行作業を大幅に効率化しますが、以下の制限事項があります。

自動変換の限界

| 項目 | 状況 |
|------|------|
| 動的 SQL | EXECUTE IMMEDIATE 内の SQL 文字列は静的解析できないため、構文変換は行われません |
| CONNECT BY 階層クエリ | WITH RECURSIVE への変換は構造が複雑なため、MANUAL 判定でガイドコメントのみ挿入されます |
| DECODE（複雑なネスト） | 単純な DECODE は CASE 変換ガイドが付きますが、深くネストした DECODE は手動確認が必要です |
| Oracle 固有パッケージ | DBMS_LOB, UTL_FILE, DBMS_SCHEDULER 等のパッケージ呼び出しは検出・警告のみ行います |
| パッケージ変数 | PL/SQL パッケージのグローバル変数はセッション変数や設定テーブルへの手動移行が必要です |
| (+) 外部結合 | 検出して REVIEW 判定しますが、LEFT JOIN / RIGHT JOIN への自動書き換えは行いません |

対象外の範囲

- データ移行 — 本ツールは DDL / DML / PL-SQL の構文変換 に特化しています。テーブルデータの移行（ETL）は [pgLoader](https://pgloader.io/) 等の専用ツールをご利用ください
- 実行時検証 — 変換後の SQL が PostgreSQL で正しく実行できるかの保証はしません。必ず PostgreSQL 環境でのテスト実行を行ってください
- Oracle 固有機能 — Database Link、Advanced Queue、Oracle Text 等の Oracle 固有ミドルウェア機能は対象外です

推奨ワークフロー


1. oracle2pg で自動変換を実行
2. HTML レポートの REVIEW / MANUAL 項目を確認
3. MANUAL 項目を手動で修正
4. PostgreSQL テスト環境で変換結果を実行・検証
5. 本番環境へ適用


> 免責事項: 本ツールの変換結果は「ベストエフォート」です。本番環境への適用前に、必ず十分なテストと DBA によるレビューを実施してください。

---

Development / 開発

テスト実行


全 39 テストを実行
pytest test_conversion.py -v

カバレッジ付き
pytest test_conversion.py --cov=src --cov-report=term-missing

Docker 内で実行
docker compose run --rm test


CI Pipeline

GitHub Actions で以下が自動実行されます（.github/workflows/ci.yml）：

1. テストジョブ — Python 3.11 / 3.12 マトリックスで pytest + coverage
2. Docker ジョブ — base / test ステージのビルド + コンテナ内テスト実行

Push / Pull Request のたびに自動的にトリガーされます。

プロジェクトのビルド


開発用インストール
pip install -e .

パッケージビルド
pip install build
python -m build


---

Contributing / 貢献について

プルリクエストを歓迎します。以下のガイドラインに沿ってご参加ください。

新しい変換ルールの追加

1. src/migration_rules.py にルールを追加します：


MigrationRule(
    rule_id="FN_030",                          # ユニークな ID（カテゴリ接頭辞 + 番号）
    category="FUNCTION",                        # DATATYPE / FUNCTION / SYNTAX / PLSQL
    severity="AUTO",                            # AUTO / REVIEW / MANUAL
    old_pattern=r"\bORACLE_FUNC\s*\(",         # Oracle 側の正規表現
    new_pattern="pg_func(",                     # PostgreSQL 側の置換文字列
    description="ORACLE_FUNC() → pg_func()",   # 英語説明
    description_ja="ORACLE_FUNC() → pg_func()",# 日本語説明
    auto_fix=True,                              # 自動置換するか
),


2. test_conversion.py にテストを追加します：


def test_function_oracle_func(self):
    result = self._transform("SELECT ORACLE_FUNC(col) FROM t;")
    self.assertIn("pg_func(", result.transformed_text)
    self.assertNotIn("ORACLE_FUNC", result.transformed_text)


3. テストが通ることを確認します：


pytest test_conversion.py -v -k "test_function_oracle_func"


ルール ID の命名規則

| 接頭辞 | カテゴリ | 例 |
|-------|---------|---|
| DT_ | DATATYPE | DT_025 |
| FN_ | FUNCTION | FN_030 |
| SX_ | SYNTAX | SX_020 |
| PL_ | PLSQL | PL_015 |
| SEQ_ | SEQUENCE | SEQ_005 |
| TR_ | TRIGGER | TR_005 |
| SYN_ | SYNONYM | SYN_003 |
| OBJ_ | OBJECT | OBJ_010 |

PR チェックリスト

- [ ] 新規ルールに対応するテストを追加した
- [ ] pytest test_conversion.py -v が全件パスする
- [ ] description と description_ja の両方を記載した
- [ ] severity を適切に設定した（確実な変換 = AUTO、要確認 = REVIEW、手動 = MANUAL）
- [ ] 既存テストが壊れていない

---

License

MIT License

Copyright (c) 2026 Oracle2PostgreSQL Contributors

---

🤝 商用利用・カスタマイズ依頼

- 個人・社内利用は無料（MIT ライセンス）
- 移行アセスメント受託、A4 PDF 診断レポート作成、独自変換ルール追加、Oracle 12c/19c/21c の特殊構文対応は応相談
- 連絡先：highdefinitionaudiodriver@gmail.com

<!-- CODEX-CURRENT-STATUS:START -->
現状サマリ (2026-05-25)

- 対象: Oracle2PostgreSQL
- 作業ブランチ: main
- README更新時点の参照コミット: 40d7fbc fix(docker): testステージのENTRYPOINTをpytestに上書きしてCIを修正
- Python プロジェクト。pyproject.toml を起点に依存関係とツール設定を管理。
- Python 実行環境向けに requirements.txt を同梱。
- Dockerfile を同梱し、コンテナ実行・検証に展開可能。
- docker-compose.yml を同梱し、ローカル統合検証に展開可能。
- docs ディレクトリ配下に設計・運用・補足資料を配置。
- src ディレクトリ配下に主要実装を配置。
- 主要な確認コマンド: python -m pytest または README 記載の Python コマンド
- 次に進めるなら、README 内の利用手順と既存 docs / tests を起点に、未整備の検証手順・引き継ぎメモ・CI 化を補強する。
<!-- CODEX-CURRENT-STATUS:END -->

------------------------------------------------------------------------
■ 動作環境
------------------------------------------------------------------------
  Windows 10/11, macOS 12+, Linux / Python 3.10 以上
  ※ オンライン専用ソフトではありません（ローカル環境で動作します）。

------------------------------------------------------------------------
■ インストール / アンインストール
------------------------------------------------------------------------
  ・本アーカイブを任意のフォルダに展開してください。
  ・詳細な起動手順は上記「ソフトの説明」および同梱の README を参照してください。
  ・アンインストールは展開したフォルダを削除するだけです（レジストリ不使用）。

------------------------------------------------------------------------
■ 転載・再配布について
------------------------------------------------------------------------
  本ソフトは MIT License のオープンソースです。同梱の LICENSE 条文に
  従う限り、自由に利用・改変・再配布できます。
  なお Vector 以外の配布サイトへの無断転載はご遠慮ください。

------------------------------------------------------------------------
■ 免責事項
------------------------------------------------------------------------
  本ソフトの使用によって生じたいかなる損害についても、作者は一切の
  責任を負いません。利用者ご自身の責任においてご使用ください。

------------------------------------------------------------------------
■ 著作権
------------------------------------------------------------------------
  Copyright (c) 2026 highdefinitionaudiodriver
  本ソフトは MIT License の下で公開されています。

------------------------------------------------------------------------
■ 連絡先 / サポート
------------------------------------------------------------------------
  作 者        : highdefinitionaudiodriver
  E-mail       : highdefinitionaudiodriver@gmail.com
  GitHub       : https://github.com/highdefinitionaudiodriver/Oracle2PostgreSQL.git
  不具合報告・ご要望は上記 E-mail もしくはリポジトリの Issues へ
  お願いいたします。

========================================================================
